Variable Recurring Payments APIs

This page is a reflection of Bank of Ireland’s implementation of the Open Banking Variable Recurring Payment APIs.

Common across VRP Payments NIGB

Known Issues

1.BOI is aware of a defect which is preventing payments being initiated to accounts with account number ‘00000000’. This is on our roadmap to fix but it is not yet possible to provide a resolution date. When a fix is scheduled and completed, updates will be published in the Transparency Calendar, here and in the News and Announcements section.

All Variable Recurring Payment version will be implemented on v3.1.10.

2.BOI is aware of the below defects and a fix for them will be implemented shortly.

List of Defects	Note
1. For VRP Sandbox consent endpoint Amount field (MaximumIndividualAmount&PeriodicLimit) does not have any length validation before decimal and after decimal currently.	A fix will be implemented shortly to have before and after decimal length validation on amount fields in periodic limits.
2. In case when x-idempotency-key Request header is not specified in POST submission API, 400 bad request will be returned with null response.	A fix will be deployed so that correct error response along with 400 bad request will be returned.
3. Optional field “Reference” in funds confirmation endpoint for VRP, will be treated as a mandatory field currently. Thus, it is mandatory for TPP to pass this field in request body for funds confirmation endpoint	A fix will be deployed so that “Reference” field will be treated as optional field as per expectations and does not return 400 bad request if not passed.
4. When optional field Reference is passed with 35 Characters or greater than 35 Characters in request body on funds confirmation endpoint it returns 200 with Error message	A fix will be implemented soon to support correct code 400 bad request along with the error message.
5. Getting 500 Internal Server error when data block is not present in request body of funds confirmation endpoint.	A fix will be implemented soon to support correct error code 400 bad request instead of 500 Internal Server error.
6. Currently, below values for PaymentContextCode is returning 400 bad request: BillingGoodsAndServicesInAdvance BillingGoodsAndServicesInArrears PispPayee EcommerceMerchantInitiatedPayment FaceToFacePointOfSale TransferToSelfTransferToThirdParty and Supported values are: BillPayment EcommerceGoods EcommerceServices Other PartyToParty	A fix will be deployed to support correct values as per open banking enumerations of PaymentContextCode.
7. Currently 500 Internal Sever error is returned when special symbol or invalid value in amount field is passed under periodic limits and MaximumIndividualAmount.	A fix will be implemented soon to support correct error code 400 bad request instead of 500 Internal Server error.
8. Currently 500 Internal Server error is returned when amount value is blank, negative or any invalid value like ABC on consent end point of confirmation of funds end point.	A fix will be implemented soon to support correct code 400 bad request instead of 500 Internal Server error.
9. Currently we are getting 500 Internal Server error when we pass amount value (blank or any invalid value like ABC) on consent end point.	A fix will be implemented soon to support correct code 400 bad request instead of 500 Internal Server error.
10. Currently 500 Internal Server error is returned when Instructed Amount block is not present in request body of VRP Submission Endpoint.	A fix will be implemented soon to support correct code 400 bad request instead of 500 Internal Server error.
11. Currently in Instructionblock, CreditorAccount details field (Schemename,Identification,SecoIdentifn,Name,SecondIdentifin,E2EIndetification) there is no validation and we are getting 201 status if we pass invalid or Blank value.	A fix will be implemented soon to support correct error handling if invalid value is passed.
12. Access Renewal Screen: Consent Re-authentication (Refresh token renewal) journey for VRP is blocked currently. It will be live soon.	A fix will be implemented soon to support consent re-authentication for VRP consents.

Payment Date

• For Banking 365 Online users, if the payment date is on Saturday, Sunday or on bank holidays, Bank of Ireland will accept the payment and process it on the next working day.
• For Business Online users, if the payment date is on Saturday, Sunday or on bank holidays, Bank of Ireland will reject the payment.

Payee Name for Bank of Ireland Business On Line

Business on Line supports payee name up to 50 characters. Request to process payment with payee name more than 50 characters will be declined.

Supported Fields

Bank of Ireland does not support the below fields in request messages:

• PSUInteractionTypes
• SupplementaryData block
• ValidFromDateTime

Bank of Ireland does not support the below fields in response messages:

• ExpectedExecutionDateTime
• ExpectedSettlementDateTime
• StatusReason
• StatusReasonDescription
• SupplementaryData Block

Supported Characters

Below is a list of special characters supported by Bank of Ireland. Bank of Ireland will reject requests received with any other character.

Special characters included in Payer Name field are confined to:

              / -  :  ' + \ Space ().,

Special characters included in Payee Name and EndToEndIdentification field are confined to:

              /  :  ' + \ Space -

Special characters included in any other field apart from above are confined to:

              / - ? : ( ) . , ' + \ Space

Supplementary information

All APIs will only return one error message in the response in case of an error scenario. Please make sure that you have provided all information that is required for a successful API call.

Scheme Name

Bank of Ireland only accepts requests with valid namespacing for Payer and Payee Scheme Name i.e. Bank of Ireland won’t be able to process values without UK.OBIE prefix.

For VRP, acceptable valid scheme names are:

• UK.OBIE.SortCodeAccountNumber
• UK.OBIE.IBAN

Requests with any other Scheme Name will be rejected.

Payment Status

For both B365 and Business Online Channel, the final status supported by Bank of Ireland for VRP is AcceptedSettlementInProcess. BOI is unable to provide the AcceptedSettlementComplete status as this is not supported in the bank’s existing online payments channels. We are aware that this may cause challenges with Open Banking / API payments and would invite TPPs to contact us if this limitation impacts them. If payment or standing order is rejected downstream, or by beneficiary bank, status will not be updated.

Local Instrument (VRP)

• Bank of Ireland UK will process VRP as next day payment.
• The supported LocalInstrument Scheme for VRP is UK.OBIE.BACS.

Confirmation of Funds for TPP (VRP)

• This API is available for both Bank of Ireland UK PLC and Bank of Ireland (ROI).
• For Banking 365 Online users and Business On Line (BOL) users, Bank of Ireland supports funds check for VRP after the user has been authenticated and authorised the vrp-consent. For accessing the confirm funds "POST" API, the Access Token must be obtained by TPP using an Authorisation Code grant type within a secure, server-side context between the TPP and the ASPSP.
• On payment submission, Bank of Ireland will perform funds check again and apply immediate debit to customer’s account. The bank will return a negative result if the user has insufficient funds in their chosen account to complete the transaction.
• If there is a change to some account statuses, due to joint account access revocation, the account being closed, or the account being downgraded due to creditstatus, the Bank TPP Confirmation of Funds API will reject the confirmation of funds request.
• The confirmation of funds request will be rejected if the request is made for a currency different from the account currency.
• Funds Check is not performed for VRP Payments i.e. the funds check does not take place at the point of authorisation or submission, but is carried out on the day the of processing.

Reverse Payments

• In the Refund block the Secondary Identification field will be populated if the account is pre-selected and secondary identification information is passed by TPPs.
• Bank of Ireland will return null for the secondary identification field in the Refund block if the account is selected at Bank’s end.

VRP Payments

Fields and Blocks Specifications for VRP on both B365 and BOL channel in Request Payload

1. Creditor Account block

• The CreditorAccount block is mandatory for VRP
• Fields mandatory for CreditorAccount block are: Identification, Name and SchemeName
• Valid SchemeName to be supported for CreditorAccount block is UK.OBIE.SortCodeAccountNumber and UK.OBIE.IBAN

2. Periodic Limits block

• Fields mandatory for PeriodicLimits block are: Amount, Currency, PeriodAlignment, and PeriodType
• Acceptable values for PeriodAlignment are: Calendar and Consent
• Acceptable values for PeriodType are: Day, Week, Fortnight, Month, Half-year, Year
• The maximum number of periodic limits that a PISP could include is 6 (one for each time period). For each period type in a single consent, period alignment can be either calendar or consent. e.g.: Max cumulative amount per calendar year and Max cumulative amount per consent year may not be an acceptable combination in one VRP consent however, Max cumulative amount per calendar year and Max cumulative amount per consent month is acceptable.

3. Control Parameters block

• Fields mandatory for ControlParameters block are: VRPType and PSUAuthenticationMethods
• Acceptable values for VRPType is: UK.OBIE.VRPType.Sweeping
• Acceptable values for PSUAuthenticationMethods is: UK.OBIE.SCANotRequired

4. Currencies

• Bank of Ireland only supports GBP.

Bank of Ireland UK VRP Payments

• For Banking 365 Online users and Business On Line (BOL) users, Bank of Ireland UK does not require payee address to post VRP Payments. If payee address is included in the VRP Payment request, it will not be considered while posting the transaction.

Payment Restrictions

The standard provides a set of control parameters that may be specified as part of the VRP Consent. These control parameters set limits for the payment orders that can be created by the TPP for a given VRP.

In addition to the control parameters defined in this standard ASPSPs may implement additional control parameters, limits and restrictions for non-sweeping VRPs.

Event Notifications

Event Notification functionality helps the TPP getting notified in case the PSU does the consent revocation at ASPSP’s end.

Event notifications for cancellation of a VRP Consent

When the PSU revokes the VRP consent at the ASPSP end, the ASPSP must inform the PISP through an event notification about the consent revocation. This is done by Aggregated Polling mechanism.

The urn:uk:org:openbanking:events:consent-authorization-revoked event should be used to indicate this. The TPP can then use the GET operation to retrieve the consent.